<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Migrating from GnomeIconList to GtkIconView</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
<link rel="home" href="index.html" title="GTK+ 2 Reference Manual">
<link rel="up" href="migrating.html" title="Part IV. Migrating from Previous Versions of GTK+">
<link rel="prev" href="new-features-GtkComboBox.html" title="New features">
<link rel="next" href="gtk-migrating-GtkAboutDialog.html" title="Migrating from GnomeAbout to GtkAboutDialog">
<meta name="generator" content="GTK-Doc V1.18 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle">
<td><a accesskey="p" href="new-features-GtkComboBox.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
<td><a accesskey="u" href="migrating.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
<th width="100%" align="center">GTK+ 2 Reference Manual</th>
<td><a accesskey="n" href="gtk-migrating-GtkAboutDialog.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
</tr></table>
<div class="chapter">
<div class="titlepage"><div><div><h2 class="title">
<a name="gtk-migrating-GtkIconView"></a>Migrating from GnomeIconList to GtkIconView</h2></div></div></div>
<p>
    Since version 2.6, GTK+ provides the <a class="link" href="GtkIconView.html" title="GtkIconView"><span class="type">GtkIconView</span></a> widget. It is similar in 
    functionality to the <span class="structname">GnomeIconList</span> widget in the 
    libgnomeui library, both widgets provide a way to lay out named icons in 
    a grid. The distinctive feature of the GTK+ widget is that it follows the 
    model-view pattern, allowing it to share the actual data (i.e. the names 
    and images of the icons) with other views.
  </p>
<p>
    <a class="link" href="GtkIconView.html" title="GtkIconView"><span class="type">GtkIconView</span></a> currently doesn't support some features found in 
    <span class="structname">GnomeIconList</span>. Icons can not be positioned freely, 
    the spacing is not customizable, and it is not possible to edit the names of 
    icons. 
  </p>
<p>
    To convert an application that uses <span class="structname">GnomeIconList</span> 
    to <a class="link" href="GtkIconView.html" title="GtkIconView"><span class="type">GtkIconView</span></a>, the first step is to organize your data in a <a class="link" href="GtkTreeModel.html" title="GtkTreeModel"><span class="type">GtkTreeModel</span></a>. 
    <span class="structname">GnomeIconList</span> lets you directly insert data with 
    <code class="function">gnome_icon_list_insert()</code> and <code class="function">gnome_icon_list_insert_pixbuf()</code> and their
    append variants. So, if you previously had a function to fill your icon 
    list similar to this one:
    </p>
<div class="informalexample">
  <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
    <tbody>
      <tr>
        <td class="listing_lines" align="right"><pre>1
2
3
4
5
6
7
8</pre></td>
        <td class="listing_code"><pre class="programlisting"><span class="type">void</span><span class="normal"> </span>
<span class="function">fill_icon_list</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">GnomeIconList</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">icon_list</span><span class="symbol">)</span>
<span class="cbracket">{</span>
<span class="normal">  </span><span class="function">gnome_icon_list_append</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">icon_list</span><span class="symbol">,</span><span class="normal"> </span><span class="string">"file1.png"</span><span class="symbol">,</span><span class="normal"> </span><span class="string">"Icon 1"</span><span class="symbol">);</span>
<span class="normal">  </span><span class="function">gnome_icon_list_append</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">icon_list</span><span class="symbol">,</span><span class="normal"> </span><span class="string">"file2.png"</span><span class="symbol">,</span><span class="normal"> </span><span class="string">"Icon 2"</span><span class="symbol">);</span>

<span class="normal">  </span><span class="comment">/* more icons ... */</span><span class="normal"> </span>
<span class="cbracket">}</span></pre></td>
      </tr>
    </tbody>
  </table>
</div>

<p>
    you will have to create a tree model, attach your icon view to it, and 
    fill the model:
    </p>
<div class="informalexample">
  <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
    <tbody>
      <tr>
        <td class="listing_lines" align="right"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50</pre></td>
        <td class="listing_code"><pre class="programlisting"><span class="keyword">enum</span><span class="normal"> </span><span class="cbracket">{</span><span class="normal"> </span>
<span class="normal">  PIXBUF_COLUMN</span><span class="symbol">,</span>
<span class="normal">  TEXT_COLUMN</span><span class="symbol">,</span>

<span class="normal">  </span><span class="comment">/* you can have more columns here, e.g */</span><span class="normal"> </span>

<span class="normal">  DATA_COLUMN</span>
<span class="cbracket">}</span><span class="symbol">;</span>
<span class="normal"> </span>
<span class="type">void</span><span class="normal"> </span>
<span class="function">fill_model</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">GtkListStore</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">store</span><span class="symbol">)</span>
<span class="cbracket">{</span>
<span class="normal">  </span><span class="usertype">GtkTreeIter</span><span class="normal"> iter</span><span class="symbol">;</span>
<span class="normal">  </span><span class="usertype">GdkPixbuf</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">pixbuf</span><span class="symbol">;</span>

<span class="normal">  </span><span class="function"><a href="GtkListStore.html#gtk-list-store-append">gtk_list_store_append</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">store</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">&amp;</span><span class="normal">iter</span><span class="symbol">);</span>
<span class="normal">  pixbuf </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="http://library.gnome.org/devel/gdk-pixbuf/unstable/gdk-pixbuf-File-Loading.html#gdk-pixbuf-new-from-file">gdk_pixbuf_new_from_file</a></span><span class="normal"> </span><span class="symbol">(</span><span class="string">"file1.png"</span><span class="symbol">,</span><span class="normal"> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">);</span>
<span class="normal">  </span><span class="function"><a href="GtkListStore.html#gtk-list-store-set">gtk_list_store_set</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">store</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">&amp;</span><span class="normal">iter</span><span class="symbol">,</span><span class="normal"> PIXBUF_COLUMN</span><span class="symbol">,</span><span class="normal"> pixbuf</span><span class="symbol">,</span><span class="normal"> TEXT_COLUMN</span><span class="symbol">,</span><span class="normal"> </span><span class="string">"Icon 1"</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">-</span><span class="number">1</span><span class="symbol">);</span>
<span class="normal">  </span><span class="function"><a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#g-object-unref">g_object_unref</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">pixbuf</span><span class="symbol">);</span>

<span class="normal">  </span><span class="function"><a href="GtkListStore.html#gtk-list-store-append">gtk_list_store_append</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">store</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">&amp;</span><span class="normal">iter</span><span class="symbol">);</span>
<span class="normal">  pixbuf </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="http://library.gnome.org/devel/gdk-pixbuf/unstable/gdk-pixbuf-File-Loading.html#gdk-pixbuf-new-from-file">gdk_pixbuf_new_from_file</a></span><span class="normal"> </span><span class="symbol">(</span><span class="string">"file2.png"</span><span class="symbol">,</span><span class="normal"> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">);</span>
<span class="normal">  </span><span class="function"><a href="GtkListStore.html#gtk-list-store-set">gtk_list_store_set</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">store</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">&amp;</span><span class="normal">iter</span><span class="symbol">,</span><span class="normal"> PIXBUF_COLUMN</span><span class="symbol">,</span><span class="normal"> pixbuf</span><span class="symbol">,</span><span class="normal"> TEXT_COLUMN</span><span class="symbol">,</span><span class="normal"> </span><span class="string">"Icon 2"</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">-</span><span class="number">1</span><span class="symbol">);</span>
<span class="normal">  </span><span class="function"><a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#g-object-unref">g_object_unref</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">pixbuf</span><span class="symbol">);</span>

<span class="normal">  </span><span class="comment">/* more icons ... */</span><span class="normal"> </span>
<span class="cbracket">}</span>

<span class="type">int</span><span class="normal"> </span>
<span class="function">main</span><span class="normal"> </span><span class="symbol">(</span><span class="type">int</span><span class="normal"> argc</span><span class="symbol">,</span><span class="normal"> </span><span class="type">char</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">argv</span><span class="symbol">[])</span>
<span class="cbracket">{</span>
<span class="normal">  </span><span class="usertype">GtkWidget</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">icon_view</span><span class="symbol">;</span>
<span class="normal">  </span><span class="usertype">GtkListStore</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">store</span><span class="symbol">;</span>

<span class="normal">  </span><span class="function"><a href="gtk-General.html#gtk-init">gtk_init</a></span><span class="normal"> </span><span class="symbol">(&amp;</span><span class="normal">argc</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">&amp;</span><span class="normal">argv</span><span class="symbol">);</span>

<span class="normal">  </span><span class="comment">/* do other initialization... */</span>

<span class="normal">  </span><span class="comment">/* construct the GtkIconView */</span>
<span class="normal">  icon_view </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="GtkIconView.html#gtk-icon-view-new">gtk_icon_view_new</a></span><span class="normal"> </span><span class="symbol">();</span>
<span class="normal">  store </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="GtkListStore.html#gtk-list-store-new">gtk_list_store_new</a></span><span class="normal"> </span><span class="symbol">(</span><span class="number">3</span><span class="symbol">,</span><span class="normal"> GDK_TYPE_PIXBUF</span><span class="symbol">,</span><span class="normal"> <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#G-TYPE-STRING:CAPS">G_TYPE_STRING</a></span><span class="symbol">,</span><span class="normal"> <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#G-TYPE-POINTER:CAPS">G_TYPE_POINTER</a></span><span class="symbol">);</span>

<span class="normal">  </span><span class="function"><a href="GtkIconView.html#gtk-icon-view-set-pixbuf-column">gtk_icon_view_set_pixbuf_column</a></span><span class="normal"> </span><span class="symbol">(</span><span class="function">GTK_ICON_VIEW</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">icon_view</span><span class="symbol">),</span><span class="normal"> PIXBUF_COLUMN</span><span class="symbol">);</span>
<span class="normal">  </span><span class="function"><a href="GtkIconView.html#gtk-icon-view-set-text-column">gtk_icon_view_set_text_column</a></span><span class="normal"> </span><span class="symbol">(</span><span class="function">GTK_ICON_VIEW</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">icon_view</span><span class="symbol">),</span><span class="normal"> TEXT_COLUMN</span><span class="symbol">);</span>
<span class="normal">  </span><span class="function"><a href="GtkIconView.html#gtk-icon-view-set-model">gtk_icon_view_set_model</a></span><span class="normal"> </span><span class="symbol">(</span><span class="function">GTK_ICON_VIEW</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">icon_view</span><span class="symbol">),</span><span class="normal"> </span><span class="function">GTK_TREE_MODEL</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">store</span><span class="symbol">));</span>

<span class="normal">  </span><span class="function">fill_model</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">store</span><span class="symbol">);</span>

<span class="normal">  </span><span class="comment">/* ... */</span>
<span class="cbracket">}</span></pre></td>
      </tr>
    </tbody>
  </table>
</div>

<p>
    This example uses a <a class="link" href="GtkListStore.html" title="GtkListStore"><span class="type">GtkListStore</span></a> as model, but part of the elegance of the 
    model-view pattern is that you can easily use another tree model implementation, 
    or even write your own custom tree model.
  </p>
<p>
    Your application may make use of extra data attached to the icons in the 
    <span class="structname">GnomeIconList</span> via <code class="function">gnome_icon_list_set_icon_data()</code> and 
    <code class="function">gnome_icon_list_get_icon_data()</code>. With <a class="link" href="GtkIconView.html" title="GtkIconView"><span class="type">GtkIconView</span></a> such data is most 
    conveniently stored in an extra column in the tree model, so you would 
    call a function like
    </p>
<div class="informalexample">
  <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
    <tbody>
      <tr>
        <td class="listing_lines" align="right"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14</pre></td>
        <td class="listing_code"><pre class="programlisting"><span class="type">void</span><span class="normal"> </span>
<span class="function">set_icon_data</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">GtkIconView</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">icon_view</span><span class="symbol">,</span>
<span class="normal">               </span><span class="usertype">gint</span><span class="normal">         idx</span><span class="symbol">,</span>
<span class="normal">               </span><span class="usertype">gpointer</span><span class="normal">     data</span><span class="symbol">)</span>
<span class="cbracket">{</span>
<span class="normal">   </span><span class="usertype">GtkTreeModel</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">model</span><span class="symbol">;</span>
<span class="normal">   </span><span class="usertype">GtkTreeIter</span><span class="normal"> iter</span><span class="symbol">;</span>

<span class="normal">   model </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="GtkIconView.html#gtk-icon-view-get-model">gtk_icon_view_get_model</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">icon_view</span><span class="symbol">);</span>

<span class="normal">   </span><span class="keyword">if</span><span class="normal"> </span><span class="symbol">(</span><span class="function"><a href="GtkTreeModel.html#gtk-tree-model-iter-nth-child">gtk_tree_model_iter_nth_child</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">model</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">&amp;</span><span class="normal">iter</span><span class="symbol">,</span><span class="normal"> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">,</span><span class="normal"> idx</span><span class="symbol">))</span>
<span class="normal">     </span><span class="function"><a href="GtkListStore.html#gtk-list-store-set">gtk_list_store_set</a></span><span class="normal"> </span><span class="symbol">(</span><span class="function">GTK_LIST_STORE</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">model</span><span class="symbol">),</span><span class="normal"> </span><span class="symbol">&amp;</span><span class="normal">iter</span><span class="symbol">,</span><span class="normal"> </span>
<span class="normal">                         DATA_COLUMN</span><span class="symbol">,</span><span class="normal"> data</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">-</span><span class="number">1</span><span class="symbol">);</span>
<span class="cbracket">}</span></pre></td>
      </tr>
    </tbody>
  </table>
</div>

<p>
    assuming that your tree model has a <code class="literal">DATA_COLUMN</code> of type 
    <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#G-TYPE-POINTER:CAPS"><code class="literal">G_TYPE_POINTER</code></a>.
  </p>
<p>
    There is a number of minor API differences between 
    <span class="structname">GnomeIconList</span> and 
    <span class="structname">GtkIconView</span>:
    </p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem"><p>
       <span class="type">GnomeIconListMode</span> is replaced by the 
       <a class="link" href="GtkIconView.html#GtkIconView--orientation" title='The "orientation" property'>orientation</a> 
       property of <span class="structname">GtkIconView</span>
     </p></li>
<li class="listitem"><p>
       <span class="structname">GtkIconView</span> can not be frozen in the same 
       way as <span class="structname">GnomeIconList</span> can with 
       <code class="function">gnome_icon_list_freeze()</code> and <code class="function">gnome_icon_list_thaw()</code>. Instead you can 
       replace the whole model of a <span class="structname">GtkIconView</span>, 
       instead of doing many small changes to the existing model.
     </p></li>
</ul></div>
<p>
  </p>
</div>
<div class="footer">
<hr>
          Generated by GTK-Doc V1.18</div>
</body>
</html>